package sjtu.rfid.rri.services.tds.pattern;

import sjtu.rfid.rri.services.tds.EPC;

/**
 * This interface defines the operations of EPCPattern compatible
 * implementations.
 * 
 * @author jinghao
 * 
 */
public interface EPCPattern {

	/**
	 * Determine whether the specified EPC matches this pattern.
	 * 
	 * @param epc
	 *            The EPC Tag to match against this pattern.
	 * @return true if the specified EPC matches this pattern, false otherwise.
	 * @throws PatternMatchException
	 *             If there was a problem during matching.
	 */
	public boolean match(EPC epc) throws PatternMatchException;

	/**
	 * <p>
	 * Determine whether the specified EPC matches this pattern and get group
	 * key for the specified epc. <br>
	 * e.g. given pattern 'urn:epc:pat:sgtin-96:3.X.X.*' and tag
	 * 'urn:epc:tag:sgtin-96:3.123.456.12345', the key will be set as
	 * "urn:epc:tag:sgtin-96:3.123.456.*" and return true.
	 * </p>
	 * <p>
	 * Caution: This method only works for group operation, it always return
	 * false if isGrouping() return false.
	 * </p>
	 * 
	 * @param epc
	 *            The EPC Tag to match against this pattern.
	 * @param key
	 *            calculates the group key for the specified epc.
	 * @return true if the specified EPC matches this pattern, false otherwise.
	 * @throws PatternMatchException
	 *             If there was a problem during matching.
	 */
	public boolean group(EPC epc, StringBuilder key)
			throws PatternMatchException;

	/**
	 * Is this Pattern object used for grouping EPC tags?
	 * 
	 * @return True if this pattern is used for grouping.
	 */
	public boolean isGrouping();

	public void setGrouping(boolean grouping);

	public boolean isPureId();

	public void setPureId(boolean pureId);

	/**
	 * Get the fully qualified URI that this Pattern instance represents.
	 * 
	 * @return A string
	 */
	public String getUri();

	public void setUri(String uri);

	/**
	 * Get the bit length of the encoding scheme. e.g. 64, 96, 128. Subclasses
	 * must implement this method to return the correct bit length.
	 * 
	 * @return The bit length of the encoding scheme.
	 */
	public int getTagBitLength();
}
